react-floater

What is react-floater?

react-floater is a lightweight and flexible library for creating tooltips, popovers, and guided tours in React applications. It provides a simple API to create floating elements that can be customized and positioned relative to other elements on the page.

What are react-floater's main functionalities?

Tooltip

This feature allows you to create a simple tooltip that appears when the user hovers over the target element. In this example, a tooltip with the text 'This is a tooltip' appears when the user hovers over the button.

import React from 'react';
import Floater from 'react-floater';

const TooltipExample = () => (
  <Floater content="This is a tooltip">
    <button>Hover me</button>
  </Floater>
);

export default TooltipExample;

Popover

This feature allows you to create a popover that can contain more complex content, such as headings and paragraphs. In this example, a popover with a title and content appears when the user clicks the button.

import React from 'react';
import Floater from 'react-floater';

const PopoverExample = () => (
  <Floater content={<div><h4>Popover Title</h4><p>This is a popover content.</p></div>}>
    <button>Click me</button>
  </Floater>
);

export default PopoverExample;

Guided Tour

This feature allows you to create a guided tour with multiple steps. Each step can target a different element on the page and display a tooltip or popover with instructions. In this example, the tour has two steps, each targeting a different element.

import React from 'react';
import Floater from 'react-floater';

const steps = [
  {
    content: 'This is the first step',
    target: '.step1'
  },
  {
    content: 'This is the second step',
    target: '.step2'
  }
];

const GuidedTourExample = () => (
  <div>
    <div className="step1">Step 1</div>
    <div className="step2">Step 2</div>
    <Floater steps={steps}>
      <button>Start Tour</button>
    </Floater>
  </div>
);

export default GuidedTourExample;

Other packages similar to react-floater

react-tooltip

react-tooltip is a popular library for creating tooltips in React applications. It offers a wide range of customization options and supports various positioning strategies. Compared to react-floater, react-tooltip is more focused on tooltips and may not offer the same level of flexibility for creating popovers and guided tours.

react-popper

react-popper is a library that provides a powerful positioning engine for creating tooltips, popovers, and dropdowns in React applications. It is built on top of the Popper.js library and offers advanced positioning capabilities. While react-popper is more powerful in terms of positioning, it may require more configuration compared to react-floater.

react-joyride

react-joyride is a library for creating guided tours in React applications. It provides a comprehensive API for defining tour steps and customizing their appearance. Compared to react-floater, react-joyride is more specialized for creating guided tours and offers more features for managing tour state and behavior.

README

React Floater

Advanced tooltips for React!

View the demo

Highlights

• 🏖 Easy to use: Just set the content
• 🛠 Flexible: Personalize the options to fit your needs
• 🟦 Typescript: Nicely typed

Usage

npm install --save react-floater

Import it in your app:

import Floater from 'react-floater';

<Floater content="This is the Floater content">
  <span>click me</span>
</Floater>;

And voíla!

Customization

You can use your own components to render the Floater with the prop component.
Check WithStyledComponents.js in the demo for an example.

If you use your own components as children it will receive an innerRef prop that you must set in your HTMLElement:

const Button = ({ innerRef, ...rest }) => <button ref={innerRef} {...rest} />;

<Floater content="This is the Floater content">
  <Button>click me</Button>
</Floater>;

This works with styled-components (and other css-in-js libraries):

const Wrapper = styled.div`
  margin: 0 auto;
  max-width: 500px;
  line-height: 1.5;
`;

<Floater content="This is the Floater content">
  <Wrapper>click me</Wrapper>
</Floater>;

Props

autoOpen?: boolean = false
Open the Floater automatically.

callback?: (action: 'open' | 'close', props: Props)
It will be called when the Floater change state.

children: React.ReactNode
An element to trigger the Floater.

component {element|function}
A React component or function to as a custom UI for the Floater.
The prop closeFloater will be available in your component.

content {node}
The Floater content. It can be anything that can be rendered.
This is the only required props, unless you pass a component.

debug {bool} ▶︎ false
Log some basic actions.
You can also set a global variable ReactFloaterDebug = true;

disableFlip {bool} ▶︎ false
Disable changes in the Floater position on scroll/resize.

disableHoverToClick {bool} ▶︎ false
Don't convert hover event to click on mobile.

event {string} ▶︎ click
The event that will trigger the Floater. It can be hover | click.
These won't work in controlled mode.

eventDelay {number} ▶︎ 0.4
The amount of time (in seconds) that the floater should wait after a mouseLeave event before hiding.
Only valid for event type hover.

footer {node}
It can be anything that can be rendered.

getPopper {function} Get the popper.js instance. It receives with 2 parameters:

• popper {object} the popper object
• origin {object} floater or wrapper

hideArrow {bool} ▶︎ false
Don't show the arrow. Useful for centered or modal layout.

offset {number} ▶︎ 15
The distance between the Floater and its target in pixels.

open {bool} The switch between normal and controlled modes.
Setting this prop will disabled the normal behavior.

options {object}
Customize popper.js modifiers.
Don't use it unless you know what you're doing

placement {string} ▶︎ bottom
The placement of the Floater. It will update the position if there's no space available.

It can be:

• top (top-start, top-end)
• bottom (bottom-start, bottom-end)
• left (left-start, left-end)
• right (right-start, right-end)
• auto
• center

portalElement {string|null|HTMLElement}
A css selector or element to render the tooltips

showCloseButton {bool} ▶︎ false
It will show a ⨉ button to close the Floater.
This will be true when you change wrapperOptions position.

styles {object} ▶︎ defaultStyles
Customize the default UI.

target {object|string}
The target used to calculate the Floater position. If it's not set, it will use the children as the target.

title {node}
It can be anything that can be rendered.

wrapperOptions {WrapperOptions}
Position the wrapper relative to the target.
You need to set a target for this to work.

interface WrapperOptions {
  offset: number; // The distance between the wrapper and the target. It can be negative.
  placement: string; // the same options as above, except center
  position: bool; // Set to true to position the wrapper
}

Styling

You can customize everything with the styles prop.
Only set the properties you want to change and the default styles will be merged.

Check the styles.ts for the syntax.

Modes

Default
The wrapper will trigger the events and use itself as the Floater's target.

<Floater content="This is the Floater content">
  <span>click me</span>
</Floater>

Proxy
The wrapper will trigger the events but the Floater will use the target prop to position itself.

<div className="App">
  <img src="some-path" />

  <Floater content="This is the Floater content" target=".App img">
    <span>click me</span>
  </Floater>
</div>

Beacon
The same as the proxy mode but the wrapper will be positioned relative to the target.

<div className="App">
  <img
    src="https://upload.wikimedia.org/wikipedia/commons/2/2d/Google-favicon-2015.png"
    width="100"
    className="my-super-image"
  />

  <Floater
    content="This is the Floater content"
    target=".my-super-image"
    wrapperOptions={{
      offset: -22,
      placement: 'top',
      position: true,
    }}
  >
    <span style={{ color: '#f04', fontSize: 34 }}>◉</span>
  </Floater>
</div>

Controlled
When you set a boolean to the open prop it will enter the controlled mode and it will not respond to events.
In this mode you don't even need to have children

<div className="App">
  <img src="some-path" />
  <Floater content="This is the Floater content" open={true} target=".App img" />
</div>